﻿<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
  
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <title>Walkthrough Part III: Generate PDF Documentation | DocFX website </title>
    <meta name="viewport" content="width=device-width">
    <meta name="title" content="Walkthrough Part III: Generate PDF Documentation | DocFX website ">
    <meta name="generator" content="docfx 2.37.0.0">
    
    <link rel="shortcut icon" href="../../favicon.ico">
    <link rel="stylesheet" href="../../styles/docfx.vendor.css">
    <link rel="stylesheet" href="../../styles/docfx.css">
    <link rel="stylesheet" href="../../styles/main.css">
    <meta property="docfx:navrel" content="../../toc.html">
    <meta property="docfx:tocrel" content="../toc.html">
    
    <meta property="docfx:rel" content="../../">
    
  </head>
  <body data-spy="scroll" data-target="#affix" data-offset="120">
    <div id="wrapper">
      <header>
        
        <nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
          <div class="container">
            <div class="navbar-header">
              <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
                <span class="sr-only">Toggle navigation</span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
              </button>
              
              <a class="navbar-brand" href="../../index.html">
                <img id="logo" class="svg" src="../../logo.svg" alt="">
              </a>
            </div>
            <div class="collapse navbar-collapse" id="navbar">
              <form class="navbar-form navbar-right" role="search" id="search">
                <div class="form-group">
                  <input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
                </div>
              </form>
            </div>
          </div>
        </nav>
        
        <div class="subnav navbar navbar-default">
          <div class="container hide-when-search" id="breadcrumb">
            <ul class="breadcrumb">
              <li></li>
            </ul>
          </div>
        </div>
      </header>
      <div class="container body-content">
        
        <div id="search-results">
          <div class="search-list"></div>
          <div class="sr-items">
            <p><i class="glyphicon glyphicon-refresh index-loading"></i></p>
          </div>
          <ul id="pagination"></ul>
        </div>
      </div>
      <div role="main" class="container body-content hide-when-search">
        
        <div class="sidenav hide-when-search">
          <a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
          <div class="sidetoggle collapse" id="sidetoggle">
            <div id="sidetoc"></div>
          </div>
        </div>
        <div class="article row grid-right">
          <div class="col-md-10">
            <article class="content wrap" id="_content" data-uid="">
<h1 id="walkthrough-part-iii-generate-pdf-documentation">Walkthrough Part III: Generate PDF Documentation</h1>

<p>After completing <a href="walkthrough_create_a_docfx_project_2.html">Walkthrough Part II: Add API Documentation to the Website</a>, we successfully create a website containing both Conceptual and API documentation. In this section, we will generate PDF files for these articles.</p>
<p>After completing walkthrough part II, our <code>D:\docfx_walkthrough\docfx_project</code> folder is in the following structure(Download the artifacts <a href="artifacts/walkthrough3.zip"><em>HERE</em></a>):</p>
<pre><code>|- articles
|- images
|- src
|- src2
|- index.md
|- toc.yml
|- docfx.json
</code></pre>
<h2 id="step0-install-prerequisite">Step0. Install prerequisite</h2>
<p>We leverage <a href="https://wkhtmltopdf.org/">wkhtmltopdf</a> to generate PDF. <a href="https://wkhtmltopdf.org/downloads.html">Download wkhtmltopdf</a> to some folder, e.g. <code>E:\Program Files\wkhtmltopdf\</code>, and save the executable folder path to <strong>%PATH%</strong> by: <code>set PATH=%PATH%;E:\Program Files\wkhtmltopdf\bin</code>.</p>
<div class="NOTE">
<h5>Note</h5>
<p>Alternativeley you can install wkhtmltopdf via <a href="https://chocolatey.org/">chocolatey</a> with <code>choco install wkhtmltopdf</code>. This will also add the executable folder to <strong>%PATH%</strong> during installation.</p>
</div>
<h2 id="step1-add-a-tocyml-specific-for-pdf">Step1. Add a toc.yml specific for PDF</h2>
<p>Current design is that each TOC file generates a corresponding PDF file, TOC is also used as the cover page of the PDF, so we create a <code>toc.yml</code> file specific for PDF under a new folder <code>pdf</code>, using <a href="http://dotnet.github.io/docfx/tutorial/intro_toc.html?q=toc%20inclu#link-to-another-toc-file">TOC Include</a> to include content from other TOC files.</p>
<pre><code class="lang-yml">- name: Articles
  href: ../articles/toc.yml
- name: Api Documentation
  href: ../api/toc.yml
- name: Another Api Documentation
  href: ../api-vb/toc.yml
</code></pre>
<h2 id="step2-add-pdf-section-into-docfxjson">Step2. Add <em>pdf</em> section into docfx.json</h2>
<p>Parameters are similar to <code>build</code> section, definitely it is using a different template (the builtin template is <code>pdf.default</code>), with another output destination. We also exclude TOC files as each TOC file generates a PDF file:</p>
<pre><code class="lang-json">...
  &quot;pdf&quot;: {
    &quot;content&quot;: [
      {
        &quot;files&quot;: [
          &quot;api/**.yml&quot;,
          &quot;api-vb/**.yml&quot;
        ],
        &quot;exclude&quot;: [
          &quot;**/toc.yml&quot;,
          &quot;**/toc.md&quot;
        ]
      },
      {
        &quot;files&quot;: [
          &quot;articles/**.md&quot;,
          &quot;articles/**/toc.yml&quot;,
          &quot;toc.yml&quot;,
          &quot;*.md&quot;,
          &quot;pdf/*&quot;
        ],
        &quot;exclude&quot;: [
          &quot;**/bin/**&quot;,
          &quot;**/obj/**&quot;,
          &quot;_site_pdf/**&quot;,
          &quot;**/toc.yml&quot;,
          &quot;**/toc.md&quot;
        ]
      },
      {
        &quot;files&quot;: &quot;pdf/toc.yml&quot;
      }
    ],
    &quot;resource&quot;: [
      {
        &quot;files&quot;: [
          &quot;images/**&quot;
        ],
        &quot;exclude&quot;: [
          &quot;**/bin/**&quot;,
          &quot;**/obj/**&quot;,
          &quot;_site_pdf/**&quot;
        ]
      }
    ],
    &quot;overwrite&quot;: [
      {
        &quot;files&quot;: [
          &quot;apidoc/**.md&quot;
        ],
        &quot;exclude&quot;: [
          &quot;**/bin/**&quot;,
          &quot;**/obj/**&quot;,
          &quot;_site_pdf/**&quot;
        ]
      }
    ],
    &quot;dest&quot;: &quot;_site_pdf&quot;
  }
</code></pre>
<p>Now, let's run <code>docfx</code>, and you can find pdf file walkthrough3_pdf.pdf generated under <code>_site_pdf</code> folder:
<img src="images/walkthrough3.png" alt="PDF Preview"></p>
<h2 id="optional-step3-enable-plugins"><em>Optional</em> Step3. Enable plugins</h2>
<p>If you wish to use plugins with pdf as well, you need to add a <code>template</code> node to the pdf section. It needs to start with the <code>pdf.template</code> followed by the path to the plugins you want to use:</p>
<pre><code class="lang-json">&quot;template&quot;: [
  &quot;pdf.default&quot;,
  &quot;pluginPackages/rest.tagpage.2.31.0/content&quot; 
],
</code></pre>
<h2 id="conclusion">Conclusion</h2>
<p>In this walkthrough, we build a PDF file according to the TOC file under <code>pdf</code> folder. Note that TOC plays an important role in PDF generation, it not only determines the files included in the PDF, but also the cover page for this PDF file. One TOC file generates one PDF file, so don't forget to exclude TOC files you don't want from docfx.json.</p>
<h2 id="read-more">Read more</h2>
<ul>
<li><p><a href="walkthrough_create_a_docfx_project.html">Walkthrough Part I: Generate a Simple Documentation Website</a></p>
</li>
<li><p><a href="walkthrough_create_a_docfx_project_2.html">Walkthrough Part II: Adding API Documentation to the Website</a></p>
</li>
<li><p><a href="advanced_walkthrough.html">Walkthrough Advanced: Customize Your Website</a></p>
</li>
</ul>
<div id="disqus_thread"></div>
                <script>
                (function() { // DON'T EDIT BELOW THIS LINE
                var d = document, s = d.createElement('script');
                s.src = 'https://docfx-github.disqus.com/embed.js';
                s.setAttribute('data-timestamp', +new Date());
                (d.head || d.body).appendChild(s);
                })();
                </script>
                <noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
            </article>
          </div>
          
          <div class="hidden-sm col-md-2" role="complementary">
            <div class="sideaffix">
              <div class="contribution">
                <ul class="nav">
                  <li>
                    <a href="#disqus_thread" class="contribution-link">0 Comments</a>
                  </li>
                </ul>
              </div>
              <nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
              <!-- <p><a class="back-to-top" href="#top">Back to top</a><p> -->
              </nav>
            </div>
          </div>
        </div>
      </div>
      
      <footer>
        <div class="grad-bottom"></div>
        <div class="footer">
          <div class="container">
            <span class="pull-right">
              <a href="#top">Back to top</a>
            </span>
            <span>Copyright © 2015-2018 Microsoft<br>Generated by <strong>DocFX</strong></span>
            
          </div>
        </div>
      </footer>
    </div>
    
    <script type="text/javascript" src="../../styles/docfx.vendor.js"></script>
    <script type="text/javascript" src="../../styles/docfx.js"></script>
    <script type="text/javascript" src="../../styles/main.js"></script>
    <script id="dsq-count-scr" src="//docfx-github.disqus.com/count.js" async=""></script>
    
    <script>
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
    
      ga('create', 'UA-99241001-1', 'auto');
      ga('send', 'pageview');
    
    </script>
  </body>
</html>
